DialogueManager

The singleton that manages dialogue execution and balloon display

The DialogueManager is an autoloaded singleton that handles dialogue execution, state management, and balloon display. It processes dialogue lines, runs mutations, and emits signals for dialogue events.

Signals

dialogue_started

signal dialogue_started(resource: DialogueResource)

Emitted when a dialogue balloon is created by DialogueManager and dialogue begins.

passed_label

signal passed_label(label: String)

Emitted when a label marker is passed through during dialogue traversal, usually when jumping from a goto line.

got_dialogue

signal got_dialogue(line: DialogueLine)

Emitted when a line of dialogue is encountered.

mutated

signal mutated(mutation: Dictionary)

Emitted when a mutation line is about to be run (not including set lines).

dialogue_ended

signal dialogue_ended(resource: DialogueResource)

Emitted when the next line of dialogue is empty, indicating the conversation has ended.

Properties

game_states

var game_states: Array = []

The list of global objects that dialogue can query. These are made available to conditions and mutations in your dialogue files.

include_singletons

var include_singletons: bool = true

Allow dialogue to call singletons (autoloads).

include_classes

var include_classes: bool = true

Allow dialogue to call static methods and properties on classes.

get_current_scene

var get_current_scene: Callable

Used to resolve the current scene. Override this if your game manages the current scene itself.

Default implementation:

func() -> Node:
    var current_scene: Node = Engine.get_main_loop().current_scene
    if current_scene == null:
        var root: Node = (Engine.get_main_loop() as SceneTree).root
        current_scene = root.get_child(root.get_child_count() - 1)
    return current_scene

Methods

show_dialogue_balloon

func show_dialogue_balloon(
    resource: DialogueResource, 
    label: String = "", 
    extra_game_states: Array = []
) -> Node

Opens the dialogue balloon configured in settings (or the example balloon if none has been set).

returns · Node

The balloon’s base node in case you want to queue_free() it yourself

Example:

DialogueManager.show_dialogue_balloon(my_dialogue, "start")

show_dialogue_balloon_scene

func show_dialogue_balloon_scene(
    balloon_scene: Node | String, 
    resource: DialogueResource, 
    label: String = "", 
    extra_game_states: Array = []
) -> Node

Opens a specific dialogue balloon scene.

returns · Node

The balloon’s base node

get_next_dialogue_line

func get_next_dialogue_line(
    resource: DialogueResource, 
    key: String = "", 
    extra_game_states: Array = [], 
    mutation_behaviour: MutationBehaviour = MutationBehaviour.Wait
) -> DialogueLine

Must be used with await.

Given a resource and label/ID, finds the next printable line of dialogue, running mutations along the way.

returns · DialogueLine

A DialogueLine object containing the dialogue data, or null if no next line is found

The example balloon only supports Wait mutation behaviour. In most cases, you should leave this as the default.

Example:

var line: DialogueLine = await DialogueManager.get_next_dialogue_line(my_dialogue, "start")
if line != null:
    print(line.character + ": " + line.text)

show_example_dialogue_balloon

func show_example_dialogue_balloon(
    resource: DialogueResource, 
    label: String = "", 
    extra_game_states: Array = []
) -> CanvasLayer

Opens the example balloon. If your game viewport is less than 400 pixels, it will open the low-res balloon. Otherwise, it will open the standard balloon. The balloon will close automatically once dialogue runs out.

returns · CanvasLayer

The example balloon’s base CanvasLayer in case you want to queue_free() it yourself

Example:

DialogueManager.show_example_dialogue_balloon(preload("res://dialogue/intro.dialogue"), "greeting")

get_line

func get_line(
    resource: DialogueResource, 
    key: String, 
    extra_game_states: Array
) -> DialogueLine

Get a specific line by its ID. This is used internally by get_next_dialogue_line().

returns · DialogueLine

The requested dialogue line, or null if not found

create_resource_from_text

func create_resource_from_text(text: String) -> Resource

Create a DialogueResource at runtime from dialogue text. Useful for dynamically generated or procedural dialogue.

returns · DialogueResource

A compiled DialogueResource, or asserts if there are syntax errors

This method will assert and fail if the dialogue text contains syntax errors. Make sure to validate your dialogue text before calling this method.

Example:

var dialogue_text = """
~ start
Nathan: Hello from runtime!
=> END
"""
var resource = DialogueManager.create_resource_from_text(dialogue_text)
var line = await resource.get_next_dialogue_line("start")

See the Runtime Generation guide for more details and use cases.

Enums

MutationBehaviour

Controls how mutation lines are processed during dialogue execution.

enum MutationBehaviour {
    Wait,        # Await mutation lines before continuing (default)
    DoNotWait,   # Run mutations but don't wait for completion
    Skip         # Skip mutation lines entirely
}

Show Usage Example

# Wait for mutations (recommended)
var line = await DialogueManager.get_next_dialogue_line(
    my_dialogue, 
    "start", 
    [], 
    DialogueManager.MutationBehaviour.Wait
)

# Don't wait for mutations (advanced use)
var line = await DialogueManager.get_next_dialogue_line(
    my_dialogue, 
    "start", 
    [], 
    DialogueManager.MutationBehaviour.DoNotWait
)